home *** CD-ROM | disk | FTP | other *** search
TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd((((3333)))) TTTTccccllll (((( )))) TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd((((3333)))) _________________________________________________________________ NNNNAAAAMMMMEEEE Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo - implement new commands in C SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>> TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd(_i_n_t_e_r_p, _c_m_d_N_a_m_e, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a, _d_e_l_e_t_e_P_r_o_c) int TTTTccccllll____DDDDeeeelllleeeetttteeeeCCCCoooommmmmmmmaaaannnndddd(_i_n_t_e_r_p, _c_m_d_N_a_m_e) int | TTTTccccllll____GGGGeeeettttCCCCoooommmmmmmmaaaannnnddddIIIInnnnffffoooo(_i_n_t_e_r_p, _c_m_d_N_a_m_e, _i_n_f_o_P_t_r) | int | TTTTccccllll____SSSSeeeettttCCCCoooommmmmmmmaaaannnnddddIIIInnnnffffoooo(_i_n_t_e_r_p, _c_m_d_N_a_m_e, _i_n_f_o_P_t_r) | AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS Tcl_Interp *_i_n_t_e_r_p (in) Interpreter in which to create new command. char *_c_m_d_N_a_m_e (in) Name of command. Tcl_CmdProc *_p_r_o_c (in) Implementation of new command: _p_r_o_c will be called whenever _c_m_d_N_a_m_e is invoked as a command. ClientData _c_l_i_e_n_t_D_a_t_a (in) Arbitrary one-word value to pass to _p_r_o_c and _d_e_l_e_t_e_P_r_o_c. Tcl_CmdDeleteProc *_d_e_l_e_t_e_P_r_o_c (in) Procedure to call before _c_m_d_N_a_m_e is deleted from the interpreter; Page 1 (printed 7/10/95) TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd((((3333)))) TTTTccccllll (((( )))) TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd((((3333)))) allows for command- specific cleanup. If NULL, then no procedure is called before the command is deleted. Tcl_CmdInfo *_i_n_f_o_P_t_r (in/out) Pointer to | structure | containing | various | information | about a Tcl | command. _________________________________________________________________ DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd defines a new command in _i_n_t_e_r_p and associates it with procedure _p_r_o_c such that whenever _c_m_d_N_a_m_e is invoked as a Tcl command (via a call to TTTTccccllll____EEEEvvvvaaaallll) the Tcl interpreter will call _p_r_o_c to process the command. If there is already a command _c_m_d_N_a_m_e associated with the interpreter, it is deleted. _P_r_o_c should have arguments and result that match the type TTTTccccllll____CCCCmmmmddddPPPPrrrroooocccc: typedef int Tcl_CmdProc( ClientData _c_l_i_e_n_t_D_a_t_a, Tcl_Interp *_i_n_t_e_r_p, int _a_r_g_c, char *_a_r_g_v[]); When _p_r_o_c is invoked the _c_l_i_e_n_t_D_a_t_a and _i_n_t_e_r_p parameters will be copies of the _c_l_i_e_n_t_D_a_t_a and _i_n_t_e_r_p arguments given to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd. Typically, _c_l_i_e_n_t_D_a_t_a points to an application-specific data structure that describes what to do when the command procedure is invoked. _A_r_g_c and _a_r_g_v describe the arguments to the command, _a_r_g_c giving the number of arguments (including the command name) and _a_r_g_v giving the values of the arguments as strings. The _a_r_g_v array will contain _a_r_g_c+1 values; the first _a_r_g_c values point to the argument strings, and the last value is NULL. _P_r_o_c must return an integer code that is either TTTTCCCCLLLL____OOOOKKKK, TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR, TTTTCCCCLLLL____RRRREEEETTTTUUUURRRRNNNN, TTTTCCCCLLLL____BBBBRRRREEEEAAAAKKKK, or TTTTCCCCLLLL____CCCCOOOONNNNTTTTIIIINNNNUUUUEEEE. See the Tcl overview man page for details on what these codes mean. Most normal commands will only return TTTTCCCCLLLL____OOOOKKKK or TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR. In addition, _p_r_o_c must set _i_n_t_e_r_p->_r_e_s_u_l_t to point to a string value; in the case of a TTTTCCCCLLLL____OOOOKKKK return code this gives the result of the command, and in the case of TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR it Page 2 (printed 7/10/95) TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd((((3333)))) TTTTccccllll (((( )))) TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd((((3333)))) gives an error message. The TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt procedure provides an easy interface for setting the return value; for complete details on how the _i_n_t_e_r_p->_r_e_s_u_l_t field is managed, see the TTTTccccllll____IIIInnnntttteeeerrrrpppp man page. Before invoking a command procedure, TTTTccccllll____EEEEvvvvaaaallll sets _i_n_t_e_r_p->_r_e_s_u_l_t to point to an empty string, so simple commands can return an empty result by doing nothing at all. The contents of the _a_r_g_v array belong to Tcl and are not | guaranteed to persist once _p_r_o_c returns: _p_r_o_c should not | modify them, nor should it set _i_n_t_e_r_p->_r_e_s_u_l_t to point | anywhere within the _a_r_g_v values. Call TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt with | status TTTTCCCCLLLL____VVVVOOOOLLLLAAAATTTTIIIILLLLEEEE if you want to return something from the | _a_r_g_v array. _D_e_l_e_t_e_P_r_o_c will be invoked when (if) _c_m_d_N_a_m_e is deleted. This can occur through a call to TTTTccccllll____DDDDeeeelllleeeetttteeeeCCCCoooommmmmmmmaaaannnndddd or TTTTccccllll____DDDDeeeelllleeeetttteeeeIIIInnnntttteeeerrrrpppp, or by replacing _c_m_d_N_a_m_e in another call to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd. _D_e_l_e_t_e_P_r_o_c is invoked before the command is deleted, and gives the application an opportunity to release any structures associated with the command. _D_e_l_e_t_e_P_r_o_c should have arguments and result that match the type TTTTccccllll____CCCCmmmmddddDDDDeeeelllleeeetttteeeePPPPrrrroooocccc: typedef void Tcl_CmdDeleteProc(ClientData _c_l_i_e_n_t_D_a_t_a); The _c_l_i_e_n_t_D_a_t_a argument will be the same as the _c_l_i_e_n_t_D_a_t_a argument passed to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd. TTTTccccllll____DDDDeeeelllleeeetttteeeeCCCCoooommmmmmmmaaaannnndddd deletes a command from a command interpreter. Once the call completes, attempts to invoke _c_m_d_N_a_m_e in _i_n_t_e_r_p will result in errors. If _c_m_d_N_a_m_e isn't bound as a command in _i_n_t_e_r_p then TTTTccccllll____DDDDeeeelllleeeetttteeeeCCCCoooommmmmmmmaaaannnndddd does nothing and returns -1; otherwise it returns 0. There are no restrictions on _c_m_d_N_a_m_e: it may refer to a built-in command, an application-specific command, or a Tcl procedure. TTTTccccllll____GGGGeeeettttCCCCoooommmmmmmmaaaannnnddddIIIInnnnffffoooo checks to see whether its _c_m_d_N_a_m_e | argument exists as a command in _i_n_t_e_r_p. If not then it | returns 0. Otherwise it places information about the | command in the structure pointed to by _i_n_f_o_P_t_r and returns | 1. Tcl_CmdInfo structures have fields named _p_r_o_c, | _c_l_i_e_n_t_D_a_t_a, and _d_e_l_e_t_e_P_r_o_c, which have the same meaning as | the corresponding arguments to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd. There is | also a field _d_e_l_e_t_e_D_a_t_a, which is the ClientData value to | pass to _d_e_l_e_t_e_P_r_o_c; it is normally the same as _c_l_i_e_n_t_D_a_t_a | but may be set independently using the TTTTccccllll____SSSSeeeettttCCCCoooommmmmmmmaaaannnnddddIIIInnnnffffoooo | procedure. | TTTTccccllll____SSSSeeeettttCCCCoooommmmmmmmaaaannnnddddIIIInnnnffffoooo is used to modify the procedures and | ClientData values associated with a command. Its _c_m_d_N_a_m_e | Page 3 (printed 7/10/95) TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd((((3333)))) TTTTccccllll (((( )))) TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd((((3333)))) argument is the name of a command in _i_n_t_e_r_p. If this | command exists then TTTTccccllll____SSSSeeeettttCCCCoooommmmmmmmaaaannnnddddIIIInnnnffffoooo returns 0. | Otherwise, it copies the information from *_i_n_f_o_P_t_r to Tcl's | internal structure for the command and returns 1. Note that | this procedure allows the ClientData for a command's | deletion procedure to be given a different value than the | ClientData for its command procedure. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS bind, command, create, delete, interpreter Page 4 (printed 7/10/95) 
